What does this PR do ?

Dev PR #4293

This PR decomposes the overloaded cuda_graph_scope field into three dedicated, semantically distinct concepts and cleans up naming throughout.

Problem

The old API overloaded --cuda-graph-scope with three unrelated concerns:

• --cuda-graph-scope full_iteration → full-iteration training graphs (a capture strategy, not a module)
• --cuda-graph-scope full_iteration_inference → block-owned inference graphs (inference ownership, not a module)
• --cuda-graph-scope attn mlp → per-layer capture regions (the actual intended use)

CudaGraphScope mixed iteration-level control flow with per-layer module selection. The three concepts have nothing in common and cannot be meaningfully combined in one field.

Solution

Four concrete changes:

1. full_iteration becomes its own cuda_graph_impl value.
   --cuda-graph-impl full_iteration replaces --cuda-graph-impl local --cuda-graph-scope full_iteration.

2. --inference-cuda-graph-scope is a new dedicated field.
   InferenceCudaGraphScope (none / layer / block) replaces full_iteration_inference in cuda_graph_scope. The default for --cuda-graph-impl local is layer (preserving prior behaviour).

3. CudaGraphScope is renamed to CudaGraphModule; cuda_graph_scope to cuda_graph_modules.
   With the two non-module values removed, the enum and field names now accurately reflect their purpose: selecting which per-layer modules to capture.

4. Normalization is centralized in cuda_graph_config.py.
   normalize_cuda_graph_modules, normalize_inference_cuda_graph_scope, and validate_deprecated_cuda_graph_modules_migration_inputs are shared between TransformerConfig.__post_init__ and validate_args, removing duplication and making the migration logic testable in isolation.

Backward compatibility

All deprecated inputs are still accepted and silently migrated at startup:

Conflicting combinations (e.g. passing both a deprecated value and the new flag with an incompatible value) are rejected with a clear assertion.

⚠️ For major changes (either in lines of code or in its impact), please make sure to first share a design doc with the team. If you're unsure what's the best way to do so, contact the @mcore-oncall.

Contribution process

Pre-checks

• I have added relevant unit tests
• I have added relevant functional tests
• I have added proper typing to my code Typing guidelines
• I have added relevant documentation
• I have run the autoformatter.sh on my PR

Code review

Feel free to message or comment the @mcore-oncall to help accelerate your merge into main. The less complex your PR is, the faster it will be approved and merged!

All PRs start as draft. If you open a non-draft PR, it will be automatically converted to draft.

Step 1: Mark PR as "Ready for Review"

1. When your PR is ready, click Ready for Review.
2. An oncall reviewer is auto-assigned and expert reviewers are notified based on your changes.
   • Some PRs may jump straight to step 2. This is determined by .github/CODEOWNERS.

⚠️ Only mark as ready once merge-conflicts are resolved and the CI is passing.
Final Review might get declined if these requirements are not fulfilled.

Step 2: Final Review

For PRs that change megatron/core, once all expert reviewers have approved, the Final Review label is applied automatically and final reviewers are assigned.

For PRs outside megatron/core, this step is skipped.

Step 3: Approved

Once all required reviewers have approved, the Approved label is applied automatically.

Merge

Any member of mcore-engineers will be able to merge your PR.